package net.openvision.util.xml;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;

import org.xml.sax.InputSource;

/**
 * Interface describing the basic functionality of an xml parser. It parses xml
 * content and builds up an application specific data structure defined by the
 * specified ElementHandler object. This application object is returned by the
 * parsing functions.
 * 
 * @author Hannes Widmoser
 * 
 */
public interface XmlParser {

	/**
	 * Parses the content of the {@see java.io.InputStream} instance specified
	 * as XML using the specified ElementHandler.
	 * 
	 * @param istream
	 *            The input stream containing the xml data.
	 * @param handler
	 *            The handler to use.
	 * @return The root object returned by the element handlers beginElement
	 *         method with the root tag as argument.
	 * @throws IOException
	 *             if an IO error occurs.
	 * @throws XmlParseException
	 *             if an error occurs during xml parsing or during mapping the
	 *             xml data to the application model through the element
	 *             handler.
	 */
	public Object parse(InputStream istream, ElementHandler handler)
			throws IOException, XmlParseException;

	/**
	 * Parses the content of the file specified as XML using the specified
	 * ElementHandler.
	 * 
	 * @param file
	 *            The file containing the xml data.
	 * @param handler
	 *            The handler to use.
	 * @return The root object returned by the element handlers beginElement
	 *         method with the root tag as argument.
	 * @throws IOException
	 *             if an IO error occurs.
	 * @throws XmlParseException
	 *             if an error occurs during xml parsing or during mapping the
	 *             xml data to the application model through the element
	 *             handler.
	 */
	public Object parse(File file, ElementHandler handler) throws IOException,
			XmlParseException;

	/**
	 * Parses the content of the {@see java.io.InputSource} instance specified
	 * as XML using the specified ElementHandler.
	 * 
	 * @param source
	 *            The input source containing the xml data.
	 * @param handler
	 *            The handler to use.
	 * @return The root object returned by the element handlers beginElement
	 *         method with the root tag as argument.
	 * @throws IOException
	 *             if an IO error occurs.
	 * @throws XmlParseException
	 *             if an error occurs during xml parsing or during mapping the
	 *             xml data to the application model through the element
	 *             handler.
	 */
	public Object parse(InputSource source, ElementHandler handler)
			throws IOException, XmlParseException;

	/**
	 * Parses the content described by the Uniform Resource Identifier (URI) as
	 * XML using the specified ElementHandler.
	 * 
	 * @param uri
	 *            The input stream containing the xml data.
	 * @param handler
	 *            The location of the content to be parsed.
	 * @return The root object returned by the element handlers beginElement
	 *         method with the root tag as argument.
	 * @throws IOException
	 *             if an IO error occurs.
	 * @throws XmlParseException
	 *             if an error occurs during xml parsing or during mapping the
	 *             xml data to the application model through the element
	 *             handler.
	 */
	public Object parse(String uri, ElementHandler handler) throws IOException,
			XmlParseException;
}
